Xceed DataGrid for Silverlight is composed of various key elements, each of which play different and important roles with the component. This topic was designed to give you an overview of these elements, the roles they play, and where you can find more information and examples of their use.
DataGridControl Class
At the core of Xceed DataGrid for Silverlight lies the DataGridControl class, which derives from Control and is used to display and manipulate data. By setting the ItemsSource property, the data from the source will be loaded into the grid and each data item will be displayed as a row. In addition, a column will be created for each property/field exposed by the data item and added to the grid's Columns collection.
How the items in a grid are selected at run time depends on the value of the SelectionMode property. If set to Single, only one item can be selected at a time. If set to Multiple, multiple items can be selected without pressing a modifier key. If set to Extended (default), multiple items can be selected but only if a modifier key is pressed. Items can also be selected by adding selection ranges to a grid's SelectedRanges property. Each range that is added to the collection represents a group of items that have matched one or more selection criteria.
 |
To learn more about selecting data, refer to the Selecting Data topic. |
Columns
For each property/field exposed by a data item, a column (see Column class) will be created and added to the grid's Columns collection. A column is not a FrameworkElement and is therefore not part of the visual tree; however, through it, various end-user interactions and cell-layout information can be defined.
Through a grid's Columns collection, all the columns in a grid, regardless of their visibility, can be accessed. The value of a column's Index property represents its position within the Columns collection while the visible position of a column can be retrieved through a column's VisiblePosition property, which may or may not correspond to the Index property.
If a column is fixed, it will always remain in the viewport. Columns are fixed according to the value of their VisiblePosition property (ignoring hidden columns) and the values of the LeftFixedColumnCount and RightFixedColumnCount properties, which indicate how many columns are fixed, to the left or right of the viewport, in the order dictated by their visible positions.
The AllowFixedColumns property (see ColumnManagerRow and DataGridControl classes) indicates whether columns can be fixed through end-user interaction. Setting the AllowFixedColumns property to false does not prevent the columns from being fixed programmatically.
Setting the grid's AutoCreateColumns property to false (by default, true) will prevent the automatic creation of columns and will require that the desired columns be added manually to the Columns collection. In the case where the AutoCreateColumns property is left to its default value and columns are manually defined in the Columns collection, the manually defined columns will appear first and they will be linked or "merged" with their automatically created equivalent. The current column, which represents the parent column of the cell that currently has the focus, can be retrieved through the grid's CurrentColumn property.
A column's AllowFilter, AllowGroup, and AllowSort properties determine whether the end user can filter, group, and sort a column's values, respectively. Setting these properties to false will prevent end-user interactions; however, these operations can still be done programmatically. Likewise, the AllowResize property dictates whether a column can be resized through end-user interactions.
The CellContentTemplate property determines how the content of the cells contained in a column are template while a new explicit cell-targeted style can be provided through the CellStyle property.
A cell editor is a control that is used to edit the content of editable cells. Each column's DataType determines which cell editor will be used, by default, to edit its cells' content; however, through the CellEditorType and CellEditorStyle properties, the default cell editors can be replaced or restyled.
|
To learn more about editing data, refer to the Editing and Inserting Data topic. |
Group descriptions have a limited lifespan within the GroupDescriptions collection, meaning that once they are removed, only a new instance can take its place. A column's GroupDescription property resolves this issue by allowing you to specify the group description that will be used whenever the data in a grid is grouped by the values of that column.
|
To learn more about grouping data, refer to the Grouping Data topic. |
Rows and Cells
Each data item that is visible in the viewport has an associated UI container (6) in which it is displayed. This container provides cells (12) in which the data items' property values are displayed and can be edited (see DataRow and DataCell classes, respectively). Similar to the CurrentColumn property, the current item can be retrieved through the grid's CurrentItem property.
Through an insertion row (4) new data items can be inserted into the grid at run time, assuming of course that it is supported by the underlying data source (see InsertionRow class). When the insertion row is not current (i.e, not inserting new data), its "Click here to insert new data..." watermark is displayed. As soon as it becomes current (i.e., new data is provided), the watermark will disappear and each cell (11) in the insertion row will be displayed (see InsertionCell class). The values in each cell can be initialized by handling the grid's CreatingNewSourceItem or NewSourceItemCreated events.
At run time, the data items that are displayed in a grid can be filtered through the use of a filter row (3) (see FilterRow class). Through each cell (10) in the filter row (see FilterCell class), values can be entered to filter the values of the corresponding column according to the selected filter operator (13). The filter expression that results from the values entered into a filter row can be retrieved through the grid's FilterExpression property. Likewise, providing a new filter expression to the FilterExpression property will update the filter row.
|
To learn more about inserting and filtering data, refer to the Inserting New Items section in the Editing and Inserting Data topic and the Filtering Data topic, respectively |
Each column header (9), which are represented by the ColumnManagerCell class, can be used to sort the values of its corresponding column, create new groups from those values, reorder, and resize the column. The row that contains the column headers (2) is represented by the ColumnManagerRow class. Through this row all sorting, resizing, and reordering operations can be prevented by setting its AllowColumnSort, AllowColumnResize, and AllowColumnReorder properties to false, respectively. These same operations can be prevented on a per-column basis by setting corresponding properties on the desired column(s).
 |
Only the column-manager row is displayed by default in the fixed headers. Both the insertion and filter rows must be added manually (see Headers and Footers topic). |
Groups and the Group-By Control
Through interactions with a group-by control (1) (see GroupByControl class), an end user can modify how the data in a grid is grouped. New groups can be created by dragging column headers into the group-by control while existing groups can be removed by clicking the "x" that is displayed in each group-by item (8) (see GroupByItem class). The order in which the items in a grid are grouped can also be modified by rearranging the group-by items that are currently displayed in the group-by control.
For each group-by item displayed in a group-by control, there is a corresponding group description (see DataGridGroupDescription class) in the grid's GroupDescriptions collection. Adding or removing group-by items from a group-by control or adding and removing group descriptions from the GroupDescriptions will be reflected in both locations.
How a group is configured is determined by its corresponding group configuration (see DataGridGroupConfiguration class). Group configurations are defined by group descriptions and will be used whenever groups are created from those descriptions. Through a group configuration, how the value of a group is displayed in the group headers (5) can be modified by providing a new DataTemplate via its GroupValueTemplate property. The style that is applied to the group header can be modified by providing a new style to its GroupHeaderStyle property. A default group configuration, which will be used for all groups whose group description does not explicitly define a group configuration, can also be provided through the DefaultGroupConfiguration property.
The group-navigation controls, which are displayed in the group headers, allows quick navigation between same-level groups by entering the name of the group to which to jump (see GroupNavigationSearchBox class) or by clicking on the next/previous buttons. If and which group-navigation controls are displayed depends on the values of the AllowGroupNavigation property and GroupNavigationModes properties. The AllowGroupNavigation property, which is defined on both the DataGridControl and DataGridGroupConfiguration classes, determines if all group-navigation controls are to be hidden. If set to false on the grid, all group-navigation controls will be hidden. If set to false on a group-configuration, the group-navigation controls will be hidden only for the groups that are based on the group configuration. The GroupNavigationModes property, which works in association with the AllowGroupNavigation property determines which of the group-navigation controls are displayed. |
To learn more about grouping data, refer to the Grouping Data topic. |
Editing and Cell Editors
How and when the data in a grid can be edited is determined through combinations of the EditTriggers and CellEditorDisplayConditions properties, which state what triggers place a grid in edit mode and when the editors, which are used to edit cell content, are displayed, respectively. By default, the EditTriggers property is set to ClickOnCurrentCell meaning that a grid will enter edit mode when the current cell is clicked, while the CellEditorDisplayConditions property is set to None, indicating that the current cell's editor will only be displayed when it is being edited. This combination of values results in a double-click action being necessary to edit the content of a cell.
A cell editor is a control that is used to edit the content of editable cells. Each column's data type determines which cell editor will be used, by default, to edit its cells' content; however, through the CellEditorType and CellEditorStyle properties, the default cell editors can be replaced or restyled.
|
To learn more about editing and cell editors, refer to the Editing and Inserting Data and Cell Editors topic, respectively. |
Notification Control
In some circumstances, one or more operations cannot complete. In these situations, a message stating what operation failed and why can be displayed in a notification control (7) (see NotificationControl class), if one is added to the header or footer section of the grid. Currently, the notification control will be displayed with a relevant message (see NotificationType enumeration) if an attempt is made to group or filter the data items while one or more items are being edited, and if the group name specified in the group-navigation control cannot be found.